GtkApplication: document relationship to gdkthreads

diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index 307ee6f84bde58bf2beba8d3c2a34996128d7fbf..b6fe1b88b5c25f039770982b59cb572f6179a861 100644 (file)
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -62,6 +62,15 @@
  * While GtkApplication works fine with plain #GtkWindows, it is recommended
  * to use it together with #GtkApplicationWindow.
  *
+ * When GDK threads are enabled, GtkApplication will acquire the GDK
+ * lock when invoking actions that arrive from other processes.  The GDK
+ * lock is not touched for local action invocations.  In order to have
+ * actions invoked in a predictable context it is therefore recommended
+ * that the GDK lock be held while invoking actions locally with
+ * g_action_group_activate_action().  The same applies to actions
+ * associated with #GtkApplicationWindow and to the 'activate' and
+ * 'open' #GApplication methods.
+ *
  * To set an application menu on a GtkApplication, use
  * g_application_set_app_menu(). The #GMenuModel that this function
  * expects is usually constructed using #GtkBuilder, as seen in the

diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 31071d76e0e0a0322aa298de898cf229b1db346a..829d959be207ef3f1d08ff1968ee8aba74d1148b 100644 (file)
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -54,6 +54,10 @@
  * prefix.  Actions must be addressed with the prefixed name when
  * referring to them from a #GMenuModel.
  *
+ * As with #GtkApplication, the GDK lock will be acquired when
+ * processing actions arriving from other processes and should therefore
+ * be held when activating actions locally (if GDK threads are enabled).
+ *
  * The settings #GtkSettings:gtk-shell-shows-app-menu and
  * #GtkSettings:gtk-shell-shows-menubar tell GTK+ whether the
  * desktop environment is showing the application menu and menubar